home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / catD / open.z / open
Encoding:
Text File  |  2002-10-03  |  14.2 KB  |  264 lines
  1.  
  2.  
  3.  
  4. ooooppppeeeennnn((((DDDD2222))))                                                              ooooppppeeeennnn((((DDDD2222))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      _oooo_pppp_eeee_nnnn - gain access to a device
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.    BBBBlllloooocccckkkk aaaannnndddd CCCChhhhaaaarrrraaaacccctttteeeerrrr SSSSyyyynnnnooooppppssssiiiissss
  13.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_tttt_yyyy_pppp_eeee_ssss_...._hhhh_>>>>
  14.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_ffff_iiii_llll_eeee_...._hhhh_>>>>
  15.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_eeee_rrrr_rrrr_nnnn_oooo_...._hhhh_>>>>
  16.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_oooo_pppp_eeee_nnnn_...._hhhh_>>>>
  17.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_cccc_rrrr_eeee_dddd_...._hhhh_>>>>
  18.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_dddd_dddd_iiii_...._hhhh_>>>>
  19.      _iiii_nnnn_tttt _p_r_e_f_i_x_oooo_pppp_eeee_nnnn_((((_dddd_eeee_vvvv______tttt _****_d_e_v_p_,,,, _iiii_nnnn_tttt _o_f_l_a_g_,,,, _iiii_nnnn_tttt _o_t_y_p_,,,, _cccc_rrrr_eeee_dddd______tttt _****_c_r_p_))))_;;;;
  20.  
  21.    BBBBlllloooocccckkkk aaaannnndddd CCCChhhhaaaarrrraaaacccctttteeeerrrr AAAArrrrgggguuuummmmeeeennnnttttssss
  22.      _d_e_v_p Pointer to a device number.
  23.  
  24.      _o_f_l_a_g
  25.           Information passed from the user that instructs the driver on how to
  26.           open the file.
  27.  
  28.      _o_t_y_p Parameter supplied so that the driver can determine how many times a
  29.           device was opened and for what reasons.
  30.  
  31.      _c_r_p  Pointer to the user credential structure.
  32.  
  33.    SSSSTTTTRRRREEEEAAAAMMMMSSSS SSSSyyyynnnnooooppppssssiiiissss
  34.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_tttt_yyyy_pppp_eeee_ssss_...._hhhh_>>>>
  35.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_ffff_iiii_llll_eeee_...._hhhh_>>>>
  36.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_ssss_tttt_rrrr_eeee_aaaa_mmmm_...._hhhh_>>>>
  37.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_eeee_rrrr_rrrr_nnnn_oooo_...._hhhh_>>>>
  38.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_cccc_rrrr_eeee_dddd_...._hhhh_>>>>
  39.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_dddd_dddd_iiii_...._hhhh_>>>>
  40.      _iiii_nnnn_tttt _p_r_e_f_i_x_oooo_pppp_eeee_nnnn_((((_qqqq_uuuu_eeee_uuuu_eeee______tttt _****_q_,,,, _dddd_eeee_vvvv______tttt _****_d_e_v_p_,,,, _iiii_nnnn_tttt _o_f_l_a_g_,,,, _iiii_nnnn_tttt _s_f_l_a_g_,,,, _cccc_rrrr_eeee_dddd______tttt _****_c_r_p_))))_;;;;
  41.  
  42.    SSSSTTTTRRRREEEEAAAAMMMMSSSS AAAArrrrgggguuuummmmeeeennnnttttssss
  43.      _q    Pointer to the queue used to reference the read side of the driver.
  44.  
  45.      _d_e_v_p Pointer to a device number.  For modules, _d_e_v_p always points to the
  46.           device number associated with the driver at the end (tail) of the
  47.           stream.
  48.  
  49.      _o_f_l_a_g
  50.           Open flags.
  51.  
  52.      _s_f_l_a_g
  53.           STREAMS flag.
  54.  
  55.      _c_r_p  Pointer to the user credential structure.
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.                                                                         PPPPaaaaggggeeee 1111
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69. ooooppppeeeennnn((((DDDD2222))))                                                              ooooppppeeeennnn((((DDDD2222))))
  70.  
  71.  
  72.  
  73.    RRRReeeettttuuuurrrrnnnn VVVVaaaalllluuuueeeessss
  74.      The _oooo_pppp_eeee_nnnn routine should return 0 for success, or the appropriate error
  75.      number.
  76.  
  77. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  78.    BBBBlllloooocccckkkk aaaannnndddd CCCChhhhaaaarrrraaaacccctttteeeerrrr DDDDeeeessssccccrrrriiiippppttttiiiioooonnnn
  79.      The driver's _oooo_pppp_eeee_nnnn routine is called to prepare a device for further
  80.      access.  It is called by the kernel during an _oooo_pppp_eeee_nnnn(2) or a _mmmm_oooo_uuuu_nnnn_tttt(2) of
  81.      the device special file.  For non-STREAMS drivers, it can also be called
  82.      from another (layered) driver.
  83.  
  84.      The bit settings for _oooo_ffff_llll_aaaa_gggg are found in _ffff_iiii_llll_eeee_...._hhhh.  Valid settings are:
  85.  
  86.           _FFFF_EEEE_XXXX_CCCC_LLLL       Interpreted in a driver-dependent manner.  Some drivers
  87.                       interpret this flag to mean open the device with
  88.                       exclusive access (fail all other attempts to open the
  89.                       device.)
  90.  
  91.           _FFFF_NNNN_DDDD_EEEE_LLLL_AAAA_YYYY     Open the device and return immediately without sleeping
  92.                       (do not block the open even if there is a problem.)
  93.  
  94.           _FFFF_NNNN_OOOO_NNNN_BBBB_LLLL_OOOO_CCCC_KKKK   Open the device and return immediately without sleeping
  95.                       (do not block the open even if there is a problem.)
  96.  
  97.           _FFFF_RRRR_EEEE_AAAA_DDDD       Open the device with read access permission.
  98.  
  99.           _FFFF_WWWW_RRRR_IIII_TTTT_EEEE      Open the device with write access permission.
  100.  
  101.      Valid values for _o_t_y_p are defined in _oooo_pppp_eeee_nnnn_...._hhhh.  The values are mutually
  102.      exclusive:
  103.  
  104.           _OOOO_TTTT_YYYY_PPPP______BBBB_LLLL_KKKK    Open occurred through block interface for the device.
  105.  
  106.           _OOOO_TTTT_YYYY_PPPP______CCCC_HHHH_RRRR    Open occurred through the raw/character interface for
  107.                       the device.
  108.  
  109.           _OOOO_TTTT_YYYY_PPPP______LLLL_YYYY_RRRR    Open a layered device.  This flag is used when one
  110.                       driver calls another driver's _oooo_pppp_eeee_nnnn routine.
  111.  
  112.    SSSSTTTTRRRREEEEAAAAMMMMSSSS DDDDeeeessssccccrrrriiiippppttttiiiioooonnnn
  113.      The STREAMS module _oooo_pppp_eeee_nnnn routine is called by the kernel during an _IIII______PPPP_UUUU_SSSS_HHHH
  114.      _iiii_oooo_cccc_tttt_llll(2).
  115.  
  116.      Values for _o_f_l_a_g are the same as those described for the block and
  117.      character open flags above.
  118.  
  119.      The values for _s_f_l_a_g are mutually exclusive:
  120.  
  121.           _CCCC_LLLL_OOOO_NNNN_EEEE_OOOO_PPPP_EEEE_NNNN   Indicates a clone open (see below.)  If the driver
  122.                       supports cloning, it must assign and return a device
  123.                       number of an unused device by changing the value of the
  124.                       device number to which _d_e_v_p points.
  125.  
  126.  
  127.  
  128.                                                                         PPPPaaaaggggeeee 2222
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135. ooooppppeeeennnn((((DDDD2222))))                                                              ooooppppeeeennnn((((DDDD2222))))
  136.  
  137.  
  138.  
  139.           _MMMM_OOOO_DDDD_OOOO_PPPP_EEEE_NNNN     Indicates that an _oooo_pppp_eeee_nnnn routine is being called for a
  140.                       module, not a driver.  This is useful in detecting
  141.                       configuration errors and in determining how the driver
  142.                       is being used, since STREAMS drivers can also be
  143.                       configured as STREAMS modules.
  144.  
  145.           _0000           Indicates a driver is being opened directly, without
  146.                       cloning.
  147.  
  148. UUUUSSSSAAAAGGGGEEEE
  149.      This entry point is required in all drivers and STREAMS modules.
  150.  
  151.      The _oooo_pppp_eeee_nnnn routine could perform any of the following general functions,
  152.      depending on the type of device and the service provided:
  153.  
  154.           enable device interrupts
  155.  
  156.           allocate buffers or other resources needed to use the device
  157.  
  158.           lock an unsharable device
  159.  
  160.           notify the device of the open
  161.  
  162.           change the device number if this is a clone open
  163.  
  164.           enable put and service procedures for multithreaded drivers
  165.  
  166.      The _oooo_pppp_eeee_nnnn routine should verify that the minor number component of _d_e_v_p is
  167.      valid, that the type of access requested by _o_t_y_p and _o_f_l_a_g is appropriate
  168.      for the device, and, if required, check permissions using the user
  169.      credentials pointed to by _c_r_p [see _dddd_rrrr_vvvv______pppp_rrrr_iiii_vvvv(D3)].
  170.  
  171.      For STREAMS drivers and modules, the _oooo_pppp_eeee_nnnn routine is called with
  172.      interrupts blocked from all STREAMS devices.  If the driver sets stream
  173.      head options by sending an _MMMM______SSSS_EEEE_TTTT_OOOO_PPPP_TTTT_SSSS message upstream from the _oooo_pppp_eeee_nnnn
  174.      routine, then the changes are guaranteed to take effect when the system
  175.      call completes.
  176.  
  177.      Support of cloning is optional.  Cloning is the process of the driver
  178.      selecting an unused device for the user.  It eliminates the need to poll
  179.      many devices when looking for an unused one.  Both STREAMS and Non-
  180.      STREAMS drivers may implement cloning behavior by changing the device
  181.      number pointed to by _d_e_v_p.  A driver may designate certain minor devices
  182.      as special clone entry points into the driver.  When these are opened,
  183.      the driver searches for an unused device and returns the new device
  184.      number by changing the value of the device number to which _d_e_v_p points.
  185.      Both the major device number and the minor device number can be changed,
  186.      although usually just the minor number is changed.  The major number is
  187.      only changed when the clone controls more than one device.
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.                                                                         PPPPaaaaggggeeee 3333
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201. ooooppppeeeennnn((((DDDD2222))))                                                              ooooppppeeeennnn((((DDDD2222))))
  202.  
  203.  
  204.  
  205.      Using this method of cloning, a STREAMS driver will never see _s_f_l_a_g set
  206.      to _CCCC_LLLL_OOOO_NNNN_EEEE_OOOO_PPPP_EEEE_NNNN.  A different method makes use of this flag.  STREAMS
  207.      drivers can take advantage of a special driver, known as the _c_l_o_n_e
  208.      _d_r_i_v_e_r, to perform clone opens.  This frees the driver from having to
  209.      reserve special minors for the clone entry points.  Here, the device node
  210.      is actually that of the clone driver (the major number is the major
  211.      number from the clone driver and the minor number is the major number
  212.      from the real driver.)  When the clone driver is opened, it will call the
  213.      real driver open routine with _s_f_l_a_g set to _CCCC_LLLL_OOOO_NNNN_EEEE_OOOO_PPPP_EEEE_NNNN.
  214.  
  215.      For STREAMS drivers and modules, for a given device number (queue), only
  216.      one instance of the _oooo_pppp_eeee_nnnn routine can be running at any given time.
  217.      However, multiple opens on any two different device numbers (queues) can
  218.      be running concurrently.  It is the responsibility of the driver or
  219.      module to synchronize access to its private data structures in this case.
  220.      For clone opens, multiple clone opens can run concurrently, and it is the
  221.      driver's responsibility to synchronize access to its private data
  222.      structures, as well as allocation and deallocation of device numbers.
  223.  
  224.    SSSSyyyynnnncccchhhhrrrroooonnnniiiizzzzaaaattttiiiioooonnnn CCCCoooonnnnssssttttrrrraaaaiiiinnnnttttssss
  225.      The _oooo_pppp_eeee_nnnn routine has user context and can sleep.  However, STREAMS
  226.      drivers and modules must sleep such that signals do not cause the sleep
  227.      to longjump [see _ssss_llll_eeee_eeee_pppp(D3)].
  228.  
  229. RRRREEEEFFFFEEEERRRREEEENNNNCCCCEEEESSSS
  230.      _cccc_llll_oooo_ssss_eeee(D2), _dddd_rrrr_vvvv______pppp_rrrr_iiii_vvvv(D3), _eeee_rrrr_rrrr_nnnn_oooo_ssss(D5), _qqqq_uuuu_eeee_uuuu_eeee(D4)
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.                                                                         PPPPaaaaggggeeee 4444
  261.  
  262.  
  263.  
  264.